Quarto, anatomy

1. Metadata: YAML

2. Text: Markdown

3. Code: knitr or jupyter

Literate programming

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. - Wikipedia

---
title: "ggplot2 demo"
date: "5/22/2021"
format: html
---

## Air Quality

There is a relationship between temperature and the ozone level.

```{r}
#| label: fig-airquality
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Metadata: YAML

“Yet Another Markup Language” or “YAML Ain’t Markup Language”

---
key: value
---

Output Options

---
format: something
---

---
format: html
---

---
format: pdf
---

---
format: revealjs
---

---
format: 
  html:
    toc: true
    code-fold: true
---

---
format: 
  html:
    option1: text
    option2: logical
---

YAML for format: html

YAML is sensitive

---
format:html # invalid, no space between
---

---
format: # invalid, read as missing
html
---

---
format: 
  html: # valid but needs next object
---

format: html # valid - there's a space

format:
  html # valid - there's 2x spaces on a new line and no trailing :

# valid - format = HTML with selections made
format: 
  html:
    toc: true

Quarto linting

Lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs. - Lint

Quarto YAML Intelligence

RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space to see all available options.

HTML options

quarto.org/docs/reference/formats/html

Rendering

1. Render in RStudio

. . .

2. System shell via quarto render

quarto render document.qmd # defaults to html
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

library(quarto)
quarto_render("document.qmd") # defaults to html
quarto_render("document.qmd", output_format = "pdf")

Text Formatting

*italics* and **bold**

superscript^2^ / subscript~2~

~~strikethrough~~

`verbatim code`

Headings

# Header 1

## Header 2

### Header 3

#### Header 4

##### Header 5

###### Header 6

Tables

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Grid tables

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

: Sample grid table.

Grid table, alignment

Alignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:

+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Bananas       | $1.34         | built-in wrapper   |
+---------------+---------------+--------------------+

For headerless tables, the colons go on the top line instead:

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+

Note that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). The RStudio IDE’s Quarto Visual Editor can assist in making these tables.

Tables from code

knitr itself can turn R dataframes into tables with knitr::kable()

A very simple table generator, and it is simple by design. It is not intended to replace any other R packages for making tables. . . .

head(mtcars) |> 
  knitr::kable()

Code

The way you treat code is very different for different contexts

Code

If you simply want code highlighting, you can use 3x backticks + the language ```r

```r
head(mtcars)
```

head(mtcars)

```{r}
#| echo: true
1 + 1
```

1 + 1

[1] 2

Code

In some scenarios you want to both execute the code and return the FULL code including backticks, like today where I’m teaching! echo: fenced is a great option for this.

```{r}
#| echo: fenced
1 + 1
```

```{r}
1 + 1
```

[1] 2

Code

If you want to, you may return purely decorative code which is not executed

````
```{{r}}
1 + 1
```
````

```{r}
1 + 1
```

Divs and Spans

Pandoc and therefore Quarto can parse “fenced Div blocks”

::: {.border}
This content can be styled with a border
:::

This is text with [special]{style="color:red;"} formatting.

::: {.unnumbered .unlisted}
Text
:::

<div style="font-size: 200px;">Text</div>

Callout Blocks

:::{.callout-note}
Note that there are five types of callouts, including: 
`note`, `tip`, `warning`, `caution`, and `important`.
:::

Callout markdown syntax

:::{.callout-note}
Note that there are five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.
:::


:::{.callout-tip}
## Tip With Caption

This is an example of a callout with a caption.
:::

:::{.callout-caution collapse="true"}
## Expand To Learn About Collapse

This is an example of a 'folded' caution callout that can be expanded by the user. You can use `collapse="true"` to collapse it by default or `collapse="false"` to make a collapsible callout that is expanded by default.
:::

Figures

Basic markdown syntax:

![Boston Terrier](images/boston-terrier.png)

Boston Terrier

Fragments

![Boston terrier](images/boston-terrier.png){fig-align="left"}

![](images/boston-terrier.png){fig-align="right" fig-alt="A photo a Boston Terrier."}

Subfigures

::: {#fig-bostons layout-ncol=2}

![Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

Two states of Howard

:::

Subfigures

Subfigures

Paths

Quarto documents reference from their existing folder/directory.

list.files(here::here())

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "_site"                   
 [5] "404.qmd"                  "choose-chinstrap.html"   
 [7] "docs"                     "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.png"             
[13] "README.md"                "workshop-conf-2022.Rproj"

Absolute vs Relative:

In other situations, like markdown, YAML or the command line/shell/terminal you’ll need to use absolute or relative file paths:

list.files("/Users/thomasmock/get-started-quarto")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "_site"                   
 [5] "404.qmd"                  "choose-chinstrap.html"   
 [7] "docs"                     "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.png"             
[13] "README.md"                "workshop-conf-2022.Rproj"

list.files("../")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "_site"                   
 [5] "404.qmd"                  "choose-chinstrap.html"   
 [7] "docs"                     "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.png"             
[13] "README.md"                "workshop-conf-2022.Rproj"

list.files("~/get-started-quarto/")

 [1] "_extensions"              "_freeze"                 
 [3] "_quarto.yml"              "_site"                   
 [5] "404.qmd"                  "choose-chinstrap.html"   
 [7] "docs"                     "index.qmd"               
 [9] "LICENSE.md"               "materials"               
[11] "preview-image-build.R"    "preview.png"             
[13] "README.md"                "workshop-conf-2022.Rproj"

Navigating in the terminal

Because Quarto is a command line interface (CLI), there are times you’ll need to use it via the terminal. A great overview of using the command line and navigating files/directories is available via the Data Carpentries or a great interactive tool for understanding commands: https://tldr.ostera.io

tldr tool

Subfigures

::: {#fig-bostons layout-nrow=2}

![Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

![Still Excited](images/boston-terrier.png){#fig-boston width="250px"}

![Still sleeping](images/boston-sleep.png){#fig-sleep width="250px"}

:::

Subfigures

Two states of Howard, twice

Subfigures

::: {layout-ncol="2"}
![Excited](images/boston-terrier.png){width="250px"}

![Sleeping](images/boston-sleep.png){width="250px"}

![Still Excited](images/boston-terrier.png){width="250px"}

![Still sleeping](images/boston-sleep.png){width="250px"}

Two states of Howard, twice
:::

Figure Divs

Note that the last paragraph in the div block is used as the figure caption.

::: {#fig-dog}

<iframe width="560" height="315" src="https://www.youtube.com/embed/iWR9gwxW-4k"></iframe>

Funny boston terrier videos
:::

Figure Divs

Footnotes

Pandoc supports numbering and formatting footnotes.

Inline footnotes

Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]

Here is an inline note.¹

Cross References

Cross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables.

![Elephant](elephant.png){#fig-elephant}

See @fig-elephant for an illustration.